<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
  		<title>Kohana Queue Documentation</title>
	</head>
	<body>
			<h1>Kohana Queue Module Documentation</h1>
			<p>The Kohana Queue Module was created by <a href="http://www.socialamp.com">SocialAmp</a>.

			<h2>Architecture</h2>
			<p>The Kohana Queue Module runs on a client server methodology. A daemon server runs in the background on your application server scanning a database for Kohana jobs to run.
			   When it finds a job to run, it loads the calling Kohana application, runs the task, and deletes it from the queue table.</p>
			<p>The Kohana Queue Module has a simple API for applications to add jobs to the queue. It has job priorities so urgent jobs can run before non-essential jobs.</p>
			<p>Any Kohana application on your server can use the Module. Just add it to the $config['modules'] array as described in the main <a href="http://docs.kohanaphp.com/general/configuration/config#modules">Kohana Documentation</a>.</p>

			<h2>The Daemon</h2>
			<p>The daemon is a stand-alone Kohana CLI application.</p>
			
			<h3>Configuration</h3>
			<p>Besides the regular Kohana config files, there is one custom config file that needs to be customized, if you wish to change the default values, application/config/queue.php. The options are:</p>
			<ul>
				<li>scan_delay: Sets the scan time of the queue daemon in seconds. The default is to scan every two seconds. If you have a busy server, you may want to make this one second.</li>
				<li>parallel_operations: This is the number of jobs the daemon will run at once. The default is 3. If your server is very fast or has lots of long jobs, you may want to increase this.</li>
			</ul>
			<p>In addition, you will need to set the following config files, <a href="http://docs.kohanaphp.com/libraries/database/configuration">database.php</a>, <a href="http://docs.kohanaphp.com/core/log#configuration">log.php</a></p>
			
			<h3>Running The Daemon</h3>
			<p>To run the daemon on your server, change to the directory you installed the module, and run <code>php index.php "application_queue/run"</code>. Alternatively, you could set this up as a startup item based on your system.</p>
			
			<h2>The Module</h2>
			<p>The module has one method to add jobs the queue:</p>
			<h3>Task_Queue::add()</h3>
			<p>This method adds a task to the queue. It has the following parameters.</p>
			<ol>
				<li>$controller_name - The full classname of the controller being called.</li>
				<li>$method_name - The full method name of the above class.</li>
				<li>$parameters - an associative array of parameters to pass to the method. Keys are the variable names of the method, and the values are the values.</li>
				<li>$priority - The priority number of this task. 1 is lowest, and 10 is the highest priority.</li>
			</ol>
			<p>Below is some example code to use the Module.</p>
			<pre>for ($i = 0; $i <= 20; $i++)
{
	$value = rand(0, 11);
	if (Task_Queue::add('Application_Queue_Controller', 'sleep', array('value' => $value), $value))
		echo '&lt;p&gt;Task added to the queue&lt;/p&gt;';
	else
		echo '&lt;p&gt;Could not add the task to the queue&lt;/p&gt;';
}</pre>
			<p>This would add the sleep() method from the Application_Queue_Controller class to the queue, with a random sleep value.</p>
	</body>
</html>